The following guide is to help the deployment of an Azure SAML configuration as the authentication provider for Pyramid. Azure has its own SAML provider settings that are subtlety different to the generic SAML.
Note: This feature is available with Enterprise licensing only.
Important: If Same Site client security is set to Strict when using SAML authentication, this may cause a loop redirect between Pyramid and the SAML provider, as cookies are prevented from working across different web domains. This shouldn't be an issue if your SAML provider and Pyramid are within the same web domain.
Azure SAML Setup
Configure Azure Portal
Start by configuring your Azure portal. From the Home page of your Azure portal, login to your Azure site, then go to Enterprise applications - All applications.
Next, click New Application and select the Non-gallery application button. Name your application and click Add.
Select the Single Sign-on tab and then select SAML.
Specify SSO Details
Enter the following details on your Azure portal single sign-on page:
- Identifier (Entity ID): Any name that is in the correct format for Azure (red arrow below).
- Reply URL (Assertion Consumer Service URL): The Pyramid website address with /login/callback - i.e. https://saml.pyramidanalytics.com/login/callback (blue arrow).
- Sign on URL: The Pyramid website address without any additions - https://saml.pyramidanalytics.com (green arrow).
- User Identifier: This should be user.userprincipalname (orange arrow).
Capture SSO URLs
Click the Configure button to open the Configure sign-on pop-out (below). Copy both the SAML Single Sign-On Service URL and the Sign-Out URL and paste into Notepad. You will need these later to configure SAML settings in Pyramid.
Save your Azure settings
Update Web.Config
Important: You must make this update on all Pyramid web servers that are running IIS.
An additional setting in IIS must be configured. By default, the web.config file can be found in the following location on all Pyramid web servers running IIS:
"C:\program files\pyramid\repository\iis\web.config"
Change your web.config file to the following:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="2147483648" />
</requestFiltering>
</security>
<rewrite>
<rules>
<rule name="ReverseProxyInboundRule1" stopProcessing="true">
<match url="(.*)" />
<action type="Rewrite" url="http://localhost:8181/{R:1}" />
</rule>
</rules>
<outboundRules>
<rule name="302" preCondition="302">
<match serverVariable="RESPONSE_Location" pattern="(.*)#redirect=(.*)" />
<action type="Rewrite" value="{R:2}" />
</rule>
<preConditions>
<preCondition name="302">
<add input="{RESPONSE_STATUS}" pattern="3[0-9][0-9]" />
</preCondition>
</preConditions>
</outboundRules>
</rewrite>
<defaultDocument>
<files>
<clear />
<add value="readme.html" />
</files>
</defaultDocument>
</system.webServer>
</configuration>Pyramid Setup
Capture SAML Settings
From the Admin console:
- From the main menu, click Security > Authentication and click Change Provider.
- From the Provider drop-down, select SAML.
If you are moving to a new authentication provider, even if you only just installed Pyramid, you need to use Change Provider. You should only change the details in the Authentication page where you are making minor changes for the same authentication provider; for example, to change a password or update a certificate.
In the SAML Settings panel in Pyramid, enter the following details as per the general SAML setup.
The details that are specific to Azure are:
- Vendor: Select Azure.
- Consumer URL: Use the sign on URL from Step 2 above.
- SAML Issuer: Use the Identifier (Entity ID) given from Step 2.
- IDP URL: Paste the SAML Single Sign-On Service URL copied in Step 3.
- Logout URL: Paste the Sign-Out URL copied in Step 3.
Specify the Initial user details
Enter the credentials for the Initial User (green highlight above). The Initial User is typically the user who is responsible for the Pyramid configuration.
Note: The new Pyramid user must have an External ID that matches the user's user.userprincipalname (UPN) in Azure Active Directory.
- User Name: The internal user name of the initial user. This is a bypass for the user when working outside of SAML.
- Password: The internal password for the user. Only used if manually logging in without the SAML framework.
- First Name: The first name of the initial user.
- Last Name: The last name of the initial user.
- Email: The email of the initial user.
- External ID: The SAML login ID of the initial user. This is typically in the format someone@domain.com and is the critical element that will enable Pyramid to match the incoming SAML assertion with the user account.
Tip: To login manually, you can use the /login/login.html or just /login entrypoints.
Get your External ID
- Click Test.
- Copy the value and paste it into the External ID field in Pyramid.
A token is generated to use as your external ID.
User Provisioning Setup
The Azure SAML provider can be used for auto provisioning in Pyramid. Click here for more details.
Save changes
Click Apply to start the provider change over process. At this stage, the existing users attached to the previous authentication system need to be converted over.
Admins will be prompted to either:
- Delete all existing users and delete their content
- Convert old users to the new provider (through the user conversion wizard), and keep their content
Since this exercise cannot be rolled back once the changes are committed, admins need to step through this exercise carefully.
- For a detailed explanation and walk-through, click here to see User Conversion